<h1 id="bufferobjects">Buffer objects</h1>

<h2>Overview of buffer types</h2>

<p>Duktape provides the following buffer and buffer-related types:</p>

<table>
<tr>
<th>Type</th>
<th>Standard</th>
<th>Duktape version</th>
<th>Description</th>
</tr>
<tr>
<td>Plain buffer</td>
<td>No<br />Duktape&nbsp;specific</td>
<td>1.0</td>
<td>Plain, primitive buffer value (not an object), similar to how a plain string relates to a String object.
    Behaves like an Uint8Array instance where possible, object coerces to an actual <code>Uint8Array</code>.</td>
</tr>
<tr>
<td>ArrayBuffer object</td>
<td>Yes<br />ES2015</td>
<td>1.3</td>
<td>Standard object type for representing a byte array.  References an underlying plain buffer.</td>
</tr>
<tr>
<td>DataView, typed array objects</td>
<td>Yes<br />ES2015</td>
<td>1.3</td>
<td>View objects to access an underlying ArrayBuffer.  References an underlying plain buffer.</td>
</tr>
<tr>
<td>Node.js Buffer object</td>
<td>No<br />Node.js-like</td>
<td>1.3</td>
<td>Object with <a href="https://nodejs.org/api/buffer.html">Node.js Buffer API</a>,
    inherits from Uint8Array.prototype.  References an underlying plain buffer.</td>
</tr>
</table>

<p>See <a href="https://github.com/svaarala/duktape/blob/master/doc/buffers.rst">buffers.rst</a>
for a detailed discussion, including a
<a href="https://github.com/svaarala/duktape/blob/master/doc/buffers.rst#summary-of-buffer-related-values">detailed table of buffer types and their properties</a>.</p>

<h2>Plain buffers</h2>

<p>Plain buffers are a non-standard memory efficient way of representing
buffer data.  Plain buffers mimic Uint8Array objects so that they inherit
from <code>Uint8Array.prototype</code>, are accepted as typed array
constructor arguments, and so on.  While plain buffers don't have a property
table and can't hold properties of their own, they have the following
virtual or inherited properties (example values are for a 24-byte buffer):</p>

<table>
<thead>
<tr>
<th>Property name</th>
<th>Example value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>[index]</td>
<td>0-255</td>
<td>Index properties in the range [0, length-1].  Reads and writes behave
    like for <code>Uint8Array</code>.</td>
</tr>
<tr>
<td class="propname">length</td>
<td>24</td>
<td>Length of buffer in bytes.  Length is not writable, so you can't resize
    a buffer by assigning its length.</td>
</tr>
<tr>
<td class="propname">byteOffset</td>
<td>0</td>
<td>Always 0, present to match typed arrays.</td>
</tr>
<tr>
<td class="propname">byteLength</td>
<td>24</td>
<td>Same as <code>.length</code>.</td>
</tr>
<tr>
<td class="propname">BYTES_PER_ELEMENT</td>
<td>1</td>
<td>Always 1, present to match typed arrays.</td>
</tr>
<tr>
<td class="propname">buffer</td>
<td>&nbsp;</td>
<td>Getter property which returns a new ArrayBuffer instance backing to the
    plain buffer without making a copy.  Because plain buffers don't have a
    property table, a new ArrayBuffer is created on every property read.
    Absent if buffer object support is disabled in Duktape configuration.</td>
</tr>
</tbody>
</table>

<p>Buffer objects like ArrayBuffer and Node.js Buffer are implemented on top
of plain buffer values and provide additional functionality like view/slice
support, typed accessors, and methods to manipulate data in different endianness.
However, they have more overhead than plain buffers.</p>

<p>For more details, see:</p>
<ul>
<li><a href="http://wiki.duktape.org/HowtoBuffers.html">How to work with buffers</a></li>
<li><a href="#typealgorithms">Type algorithms</a></li>
<li><a href="https://github.com/svaarala/duktape/blob/master/doc/buffers.rst">buffers.rst</a></li>
</ul>

<h2>Working with buffers</h2>

<p>Buffer values work in both C and ECMAScript code:</p>

<ul>
<li>For ECMAScript code most of the behavior is defined in the relevant API
    standards, with exceptions for Duktape-specific features like mixing
    different buffer types.</li>
<li>For C code there are API calls to work with
    <a href="api.html#taglist-buffer">plain buffers</a> and
    <a href="api.html#taglist-bufferobject">buffer objects</a>.</li>
</ul>

<p>See
<a href="http://wiki.duktape.org/HowtoBuffers.html">How to work with buffers</a>
for examples.</p>

<div class="note">
In special cases the plain buffer backing a buffer object may not be large
enough to cover the apparent size of the buffer object; the buffer object
is then "uncovered" or "unbacked".  Duktape guarantees memory safe behavior
for such buffers, but other than that behavior varies between calls.  For
example, a call may ignore the situation silently returning undefined, NaN,
or zero, or it may throw a TypeError.  <b>The behavior for unbacked buffers is
not part of versioning guarantees and may change between minor versions.</b>
</div>

<h2>Current limitations</h2>

<ul>
<li>See <a href="#typedarray-custombehavior">TypedArray binding</a> custom
    behavior.</li>
<li>See <a href="#nodejsbuffer-custombehavior">Node.js Buffer binding</a> custom
    behavior.</li>
</ul>
